
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>The “sites” framework &#8212; Django 1.11.22.dev20190603194737 documentation</title>
    <link rel="stylesheet" href="../../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="The staticfiles app" href="staticfiles.html" />
    <link rel="prev" title="The sitemap framework" href="sitemaps.html" />



 
<script type="text/javascript" src="../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);
</script>


  </head><body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../index.html">Django 1.11.22.dev20190603194737 documentation</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../index.html">Home</a>  |
        <a title="Table of contents" href="../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../genindex.html">Index</a>  |
        <a title="Module index" href="../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="sitemaps.html" title="The sitemap framework">previous</a>
     |
    <a href="../index.html" title="API Reference" accesskey="U">up</a>
   |
    <a href="staticfiles.html" title="The &lt;code class=&#34;docutils literal notranslate&#34;&gt;&lt;span class=&#34;pre&#34;&gt;staticfiles&lt;/span&gt;&lt;/code&gt; app">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="ref-contrib-sites">
            
  <div class="section" id="s-module-django.contrib.sites">
<span id="s-the-sites-framework"></span><span id="module-django.contrib.sites"></span><span id="the-sites-framework"></span><h1>The “sites” framework<a class="headerlink" href="#module-django.contrib.sites" title="Permalink to this headline">¶</a></h1>
<p>Django comes with an optional “sites” framework. It’s a hook for associating
objects and functionality to particular websites, and it’s a holding place for
the domain names and “verbose” names of your Django-powered sites.</p>
<p>Use it if your single Django installation powers more than one site and you
need to differentiate between those sites in some way.</p>
<p>The sites framework is mainly based on a simple model:</p>
<dl class="class">
<dt id="django.contrib.sites.models.Site">
<em class="property">class </em><code class="descclassname">models.</code><code class="descname">Site</code><a class="headerlink" href="#django.contrib.sites.models.Site" title="Permalink to this definition">¶</a></dt>
<dd><p>A model for storing the <code class="docutils literal notranslate"><span class="pre">domain</span></code> and <code class="docutils literal notranslate"><span class="pre">name</span></code> attributes of a website.</p>
<dl class="attribute">
<dt id="django.contrib.sites.models.Site.domain">
<code class="descname">domain</code><a class="headerlink" href="#django.contrib.sites.models.Site.domain" title="Permalink to this definition">¶</a></dt>
<dd><p>The fully qualified domain name associated with the website.
For example, <code class="docutils literal notranslate"><span class="pre">www.example.com</span></code>.</p>
</dd></dl>

<dl class="attribute">
<dt id="django.contrib.sites.models.Site.name">
<code class="descname">name</code><a class="headerlink" href="#django.contrib.sites.models.Site.name" title="Permalink to this definition">¶</a></dt>
<dd><p>A human-readable “verbose” name for the website.</p>
</dd></dl>

</dd></dl>

<p>The <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SITE_ID</span></code></a> setting specifies the database ID of the
<a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a> object associated with that
particular settings file. If the setting is omitted, the
<a class="reference internal" href="#django.contrib.sites.shortcuts.get_current_site" title="django.contrib.sites.shortcuts.get_current_site"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_current_site()</span></code></a> function will
try to get the current site by comparing the
<a class="reference internal" href="#django.contrib.sites.models.Site.domain" title="django.contrib.sites.models.Site.domain"><code class="xref py py-attr docutils literal notranslate"><span class="pre">domain</span></code></a> with the host name from
the <a class="reference internal" href="../request-response.html#django.http.HttpRequest.get_host" title="django.http.HttpRequest.get_host"><code class="xref py py-meth docutils literal notranslate"><span class="pre">request.get_host()</span></code></a> method.</p>
<p>How you use this is up to you, but Django uses it in a couple of ways
automatically via simple conventions.</p>
<div class="section" id="s-example-usage">
<span id="example-usage"></span><h2>Example usage<a class="headerlink" href="#example-usage" title="Permalink to this headline">¶</a></h2>
<p>Why would you use sites? It’s best explained through examples.</p>
<div class="section" id="s-associating-content-with-multiple-sites">
<span id="associating-content-with-multiple-sites"></span><h3>Associating content with multiple sites<a class="headerlink" href="#associating-content-with-multiple-sites" title="Permalink to this headline">¶</a></h3>
<p>The Django-powered sites <a class="reference external" href="http://www.ljworld.com/">LJWorld.com</a> and <a class="reference external" href="http://www.lawrence.com/">Lawrence.com</a> are operated by the
same news organization – the Lawrence Journal-World newspaper in Lawrence,
Kansas. LJWorld.com focuses on news, while Lawrence.com focuses on local
entertainment. But sometimes editors want to publish an article on <em>both</em>
sites.</p>
<p>The naive way of solving the problem would be to require site producers to
publish the same story twice: once for LJWorld.com and again for Lawrence.com.
But that’s inefficient for site producers, and it’s redundant to store
multiple copies of the same story in the database.</p>
<p>The better solution is simple: Both sites use the same article database, and an
article is associated with one or more sites. In Django model terminology,
that’s represented by a <a class="reference internal" href="../models/fields.html#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><code class="xref py py-class docutils literal notranslate"><span class="pre">ManyToManyField</span></code></a> in the
<code class="docutils literal notranslate"><span class="pre">Article</span></code> model:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db</span> <span class="k">import</span> <span class="n">models</span>
<span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="k">import</span> <span class="n">Site</span>

<span class="k">class</span> <span class="nc">Article</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="n">headline</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">200</span><span class="p">)</span>
    <span class="c1"># ...</span>
    <span class="n">sites</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ManyToManyField</span><span class="p">(</span><span class="n">Site</span><span class="p">)</span>
</pre></div>
</div>
<p>This accomplishes several things quite nicely:</p>
<ul>
<li><p class="first">It lets the site producers edit all content – on both sites – in a
single interface (the Django admin).</p>
</li>
<li><p class="first">It means the same story doesn’t have to be published twice in the
database; it only has a single record in the database.</p>
</li>
<li><p class="first">It lets the site developers use the same Django view code for both sites.
The view code that displays a given story just checks to make sure the
requested story is on the current site. It looks something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.contrib.sites.shortcuts</span> <span class="k">import</span> <span class="n">get_current_site</span>

<span class="k">def</span> <span class="nf">article_detail</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">article_id</span><span class="p">):</span>
    <span class="k">try</span><span class="p">:</span>
        <span class="n">a</span> <span class="o">=</span> <span class="n">Article</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="n">article_id</span><span class="p">,</span> <span class="n">sites__id</span><span class="o">=</span><span class="n">get_current_site</span><span class="p">(</span><span class="n">request</span><span class="p">)</span><span class="o">.</span><span class="n">id</span><span class="p">)</span>
    <span class="k">except</span> <span class="n">Article</span><span class="o">.</span><span class="n">DoesNotExist</span><span class="p">:</span>
        <span class="k">raise</span> <span class="n">Http404</span><span class="p">(</span><span class="s2">&quot;Article does not exist on this site&quot;</span><span class="p">)</span>
    <span class="c1"># ...</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="s-associating-content-with-a-single-site">
<span id="associating-content-with-a-single-site"></span><h3>Associating content with a single site<a class="headerlink" href="#associating-content-with-a-single-site" title="Permalink to this headline">¶</a></h3>
<p>Similarly, you can associate a model to the
<a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a>
model in a many-to-one relationship, using
<a class="reference internal" href="../models/fields.html#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate"><span class="pre">ForeignKey</span></code></a>.</p>
<p>For example, if an article is only allowed on a single site, you’d use a model
like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db</span> <span class="k">import</span> <span class="n">models</span>
<span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="k">import</span> <span class="n">Site</span>

<span class="k">class</span> <span class="nc">Article</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="n">headline</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">200</span><span class="p">)</span>
    <span class="c1"># ...</span>
    <span class="n">site</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">Site</span><span class="p">,</span> <span class="n">on_delete</span><span class="o">=</span><span class="n">models</span><span class="o">.</span><span class="n">CASCADE</span><span class="p">)</span>
</pre></div>
</div>
<p>This has the same benefits as described in the last section.</p>
</div>
<div class="section" id="s-hooking-into-the-current-site-from-views">
<span id="s-hooking-into-current-site-from-views"></span><span id="hooking-into-the-current-site-from-views"></span><span id="hooking-into-current-site-from-views"></span><h3>Hooking into the current site from views<a class="headerlink" href="#hooking-into-the-current-site-from-views" title="Permalink to this headline">¶</a></h3>
<p>You can use the sites framework in your Django views to do
particular things based on the site in which the view is being called.
For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.conf</span> <span class="k">import</span> <span class="n">settings</span>

<span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="k">if</span> <span class="n">settings</span><span class="o">.</span><span class="n">SITE_ID</span> <span class="o">==</span> <span class="mi">3</span><span class="p">:</span>
        <span class="c1"># Do something.</span>
        <span class="k">pass</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="c1"># Do something else.</span>
        <span class="k">pass</span>
</pre></div>
</div>
<p>Of course, it’s ugly to hard-code the site IDs like that. This sort of
hard-coding is best for hackish fixes that you need done quickly. The
cleaner way of accomplishing the same thing is to check the current site’s
domain:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.contrib.sites.shortcuts</span> <span class="k">import</span> <span class="n">get_current_site</span>

<span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="n">current_site</span> <span class="o">=</span> <span class="n">get_current_site</span><span class="p">(</span><span class="n">request</span><span class="p">)</span>
    <span class="k">if</span> <span class="n">current_site</span><span class="o">.</span><span class="n">domain</span> <span class="o">==</span> <span class="s1">&#39;foo.com&#39;</span><span class="p">:</span>
        <span class="c1"># Do something</span>
        <span class="k">pass</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="c1"># Do something else.</span>
        <span class="k">pass</span>
</pre></div>
</div>
<p>This has also the advantage of checking if the sites framework is installed,
and return a <a class="reference internal" href="#django.contrib.sites.requests.RequestSite" title="django.contrib.sites.requests.RequestSite"><code class="xref py py-class docutils literal notranslate"><span class="pre">RequestSite</span></code></a> instance if
it is not.</p>
<p>If you don’t have access to the request object, you can use the
<code class="docutils literal notranslate"><span class="pre">get_current()</span></code> method of the <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a>
model’s manager. You should then ensure that your settings file does contain
the <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SITE_ID</span></code></a> setting. This example is equivalent to the previous one:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="k">import</span> <span class="n">Site</span>

<span class="k">def</span> <span class="nf">my_function_without_request</span><span class="p">():</span>
    <span class="n">current_site</span> <span class="o">=</span> <span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span>
    <span class="k">if</span> <span class="n">current_site</span><span class="o">.</span><span class="n">domain</span> <span class="o">==</span> <span class="s1">&#39;foo.com&#39;</span><span class="p">:</span>
        <span class="c1"># Do something</span>
        <span class="k">pass</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="c1"># Do something else.</span>
        <span class="k">pass</span>
</pre></div>
</div>
</div>
<div class="section" id="s-getting-the-current-domain-for-display">
<span id="getting-the-current-domain-for-display"></span><h3>Getting the current domain for display<a class="headerlink" href="#getting-the-current-domain-for-display" title="Permalink to this headline">¶</a></h3>
<p>LJWorld.com and Lawrence.com both have email alert functionality, which lets
readers sign up to get notifications when news happens. It’s pretty basic: A
reader signs up on a Web form and immediately gets an email saying,
“Thanks for your subscription.”</p>
<p>It’d be inefficient and redundant to implement this sign up processing code
twice, so the sites use the same code behind the scenes. But the “thank you for
signing up” notice needs to be different for each site. By using
<a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a>
objects, we can abstract the “thank you” notice to use the values of the
current site’s <a class="reference internal" href="#django.contrib.sites.models.Site.name" title="django.contrib.sites.models.Site.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a> and
<a class="reference internal" href="#django.contrib.sites.models.Site.domain" title="django.contrib.sites.models.Site.domain"><code class="xref py py-attr docutils literal notranslate"><span class="pre">domain</span></code></a>.</p>
<p>Here’s an example of what the form-handling view looks like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.contrib.sites.shortcuts</span> <span class="k">import</span> <span class="n">get_current_site</span>
<span class="kn">from</span> <span class="nn">django.core.mail</span> <span class="k">import</span> <span class="n">send_mail</span>

<span class="k">def</span> <span class="nf">register_for_newsletter</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="c1"># Check form values, etc., and subscribe the user.</span>
    <span class="c1"># ...</span>

    <span class="n">current_site</span> <span class="o">=</span> <span class="n">get_current_site</span><span class="p">(</span><span class="n">request</span><span class="p">)</span>
    <span class="n">send_mail</span><span class="p">(</span>
        <span class="s1">&#39;Thanks for subscribing to </span><span class="si">%s</span><span class="s1"> alerts&#39;</span> <span class="o">%</span> <span class="n">current_site</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
        <span class="s1">&#39;Thanks for your subscription. We appreciate it.</span><span class="se">\n\n</span><span class="s1">-The </span><span class="si">%s</span><span class="s1"> team.&#39;</span> <span class="o">%</span> <span class="p">(</span>
            <span class="n">current_site</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
        <span class="p">),</span>
        <span class="s1">&#39;editor@</span><span class="si">%s</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">current_site</span><span class="o">.</span><span class="n">domain</span><span class="p">,</span>
        <span class="p">[</span><span class="n">user</span><span class="o">.</span><span class="n">email</span><span class="p">],</span>
    <span class="p">)</span>

    <span class="c1"># ...</span>
</pre></div>
</div>
<p>On Lawrence.com, this email has the subject line “Thanks for subscribing to
lawrence.com alerts.” On LJWorld.com, the email has the subject “Thanks for
subscribing to LJWorld.com alerts.” Same goes for the email’s message body.</p>
<p>Note that an even more flexible (but more heavyweight) way of doing this would
be to use Django’s template system. Assuming Lawrence.com and LJWorld.com have
different template directories (<a class="reference internal" href="../settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DIRS</span></code></a>), you could
simply farm out to the template system like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.core.mail</span> <span class="k">import</span> <span class="n">send_mail</span>
<span class="kn">from</span> <span class="nn">django.template</span> <span class="k">import</span> <span class="n">loader</span><span class="p">,</span> <span class="n">Context</span>

<span class="k">def</span> <span class="nf">register_for_newsletter</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="c1"># Check form values, etc., and subscribe the user.</span>
    <span class="c1"># ...</span>

    <span class="n">subject</span> <span class="o">=</span> <span class="n">loader</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="s1">&#39;alerts/subject.txt&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">Context</span><span class="p">({}))</span>
    <span class="n">message</span> <span class="o">=</span> <span class="n">loader</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="s1">&#39;alerts/message.txt&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">Context</span><span class="p">({}))</span>
    <span class="n">send_mail</span><span class="p">(</span><span class="n">subject</span><span class="p">,</span> <span class="n">message</span><span class="p">,</span> <span class="s1">&#39;editor@ljworld.com&#39;</span><span class="p">,</span> <span class="p">[</span><span class="n">user</span><span class="o">.</span><span class="n">email</span><span class="p">])</span>

    <span class="c1"># ...</span>
</pre></div>
</div>
<p>In this case, you’d have to create <code class="file docutils literal notranslate"><span class="pre">subject.txt</span></code> and <code class="file docutils literal notranslate"><span class="pre">message.txt</span></code>
template files for both the LJWorld.com and Lawrence.com template directories.
That gives you more flexibility, but it’s also more complex.</p>
<p>It’s a good idea to exploit the <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a>
objects as much as possible, to remove unneeded complexity and redundancy.</p>
</div>
<div class="section" id="s-getting-the-current-domain-for-full-urls">
<span id="getting-the-current-domain-for-full-urls"></span><h3>Getting the current domain for full URLs<a class="headerlink" href="#getting-the-current-domain-for-full-urls" title="Permalink to this headline">¶</a></h3>
<p>Django’s <code class="docutils literal notranslate"><span class="pre">get_absolute_url()</span></code> convention is nice for getting your objects’
URL without the domain name, but in some cases you might want to display the
full URL – with <code class="docutils literal notranslate"><span class="pre">http://</span></code> and the domain and everything – for an object.
To do this, you can use the sites framework. A simple example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="k">import</span> <span class="n">Site</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">obj</span> <span class="o">=</span> <span class="n">MyModel</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">obj</span><span class="o">.</span><span class="n">get_absolute_url</span><span class="p">()</span>
<span class="go">&#39;/mymodel/objects/3/&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span><span class="o">.</span><span class="n">domain</span>
<span class="go">&#39;example.com&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="s1">&#39;https://</span><span class="si">%s%s</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span><span class="o">.</span><span class="n">domain</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">get_absolute_url</span><span class="p">())</span>
<span class="go">&#39;https://example.com/mymodel/objects/3/&#39;</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-enabling-the-sites-framework">
<span id="s-id1"></span><span id="enabling-the-sites-framework"></span><span id="id1"></span><h2>Enabling the sites framework<a class="headerlink" href="#enabling-the-sites-framework" title="Permalink to this headline">¶</a></h2>
<p>To enable the sites framework, follow these steps:</p>
<ol class="arabic">
<li><p class="first">Add <code class="docutils literal notranslate"><span class="pre">'django.contrib.sites'</span></code> to your <a class="reference internal" href="../settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">INSTALLED_APPS</span></code></a>
setting.</p>
</li>
<li><p class="first">Define a <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SITE_ID</span></code></a> setting:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SITE_ID</span> <span class="o">=</span> <span class="mi">1</span>
</pre></div>
</div>
</li>
<li><p class="first">Run <a class="reference internal" href="../django-admin.html#django-admin-migrate"><code class="xref std std-djadmin docutils literal notranslate"><span class="pre">migrate</span></code></a>.</p>
</li>
</ol>
<p><code class="docutils literal notranslate"><span class="pre">django.contrib.sites</span></code> registers a
<a class="reference internal" href="../signals.html#django.db.models.signals.post_migrate" title="django.db.models.signals.post_migrate"><code class="xref py py-data docutils literal notranslate"><span class="pre">post_migrate</span></code></a> signal handler which creates a
default site named <code class="docutils literal notranslate"><span class="pre">example.com</span></code> with the domain <code class="docutils literal notranslate"><span class="pre">example.com</span></code>. This site
will also be created after Django creates the test database. To set the
correct name and domain for your project, you can use a <a class="reference internal" href="../../topics/migrations.html#data-migrations"><span class="std std-ref">data migration</span></a>.</p>
<p>In order to serve different sites in production, you’d create a separate
settings file with each <code class="docutils literal notranslate"><span class="pre">SITE_ID</span></code> (perhaps importing from a common settings
file to avoid duplicating shared settings) and then specify the appropriate
<span class="target" id="index-0"></span><a class="reference internal" href="../../topics/settings.html#envvar-DJANGO_SETTINGS_MODULE"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">DJANGO_SETTINGS_MODULE</span></code></a> for each site.</p>
</div>
<div class="section" id="s-caching-the-current-site-object">
<span id="caching-the-current-site-object"></span><h2>Caching the current <code class="docutils literal notranslate"><span class="pre">Site</span></code> object<a class="headerlink" href="#caching-the-current-site-object" title="Permalink to this headline">¶</a></h2>
<p>As the current site is stored in the database, each call to
<code class="docutils literal notranslate"><span class="pre">Site.objects.get_current()</span></code> could result in a database query. But Django is a
little cleverer than that: on the first request, the current site is cached, and
any subsequent call returns the cached data instead of hitting the database.</p>
<p>If for any reason you want to force a database query, you can tell Django to
clear the cache using <code class="docutils literal notranslate"><span class="pre">Site.objects.clear_cache()</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># First call; current site fetched from database.</span>
<span class="n">current_site</span> <span class="o">=</span> <span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span>
<span class="c1"># ...</span>

<span class="c1"># Second call; current site fetched from cache.</span>
<span class="n">current_site</span> <span class="o">=</span> <span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span>
<span class="c1"># ...</span>

<span class="c1"># Force a database query for the third call.</span>
<span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">clear_cache</span><span class="p">()</span>
<span class="n">current_site</span> <span class="o">=</span> <span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="section" id="s-the-currentsitemanager">
<span id="the-currentsitemanager"></span><h2>The <code class="docutils literal notranslate"><span class="pre">CurrentSiteManager</span></code><a class="headerlink" href="#the-currentsitemanager" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="django.contrib.sites.managers.CurrentSiteManager">
<em class="property">class </em><code class="descclassname">managers.</code><code class="descname">CurrentSiteManager</code><a class="headerlink" href="#django.contrib.sites.managers.CurrentSiteManager" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>If <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a> plays a key role in your
application, consider using the helpful
<a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><code class="xref py py-class docutils literal notranslate"><span class="pre">CurrentSiteManager</span></code></a> in your
model(s). It’s a model <a class="reference internal" href="../../topics/db/managers.html"><span class="doc">manager</span></a> that
automatically filters its queries to include only objects associated
with the current <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a>.</p>
<div class="admonition-mandatory-setting-site-id admonition">
<p class="first admonition-title">Mandatory <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SITE_ID</span></code></a></p>
<p class="last">The <code class="docutils literal notranslate"><span class="pre">CurrentSiteManager</span></code> is only usable when the <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SITE_ID</span></code></a>
setting is defined in your settings.</p>
</div>
<p>Use <a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><code class="xref py py-class docutils literal notranslate"><span class="pre">CurrentSiteManager</span></code></a> by adding it to
your model explicitly. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db</span> <span class="k">import</span> <span class="n">models</span>
<span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="k">import</span> <span class="n">Site</span>
<span class="kn">from</span> <span class="nn">django.contrib.sites.managers</span> <span class="k">import</span> <span class="n">CurrentSiteManager</span>

<span class="k">class</span> <span class="nc">Photo</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="n">photo</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">FileField</span><span class="p">(</span><span class="n">upload_to</span><span class="o">=</span><span class="s1">&#39;photos&#39;</span><span class="p">)</span>
    <span class="n">photographer_name</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    <span class="n">pub_date</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">DateField</span><span class="p">()</span>
    <span class="n">site</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">Site</span><span class="p">,</span> <span class="n">on_delete</span><span class="o">=</span><span class="n">models</span><span class="o">.</span><span class="n">CASCADE</span><span class="p">)</span>
    <span class="n">objects</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">Manager</span><span class="p">()</span>
    <span class="n">on_site</span> <span class="o">=</span> <span class="n">CurrentSiteManager</span><span class="p">()</span>
</pre></div>
</div>
<p>With this model, <code class="docutils literal notranslate"><span class="pre">Photo.objects.all()</span></code> will return all <code class="docutils literal notranslate"><span class="pre">Photo</span></code> objects in
the database, but <code class="docutils literal notranslate"><span class="pre">Photo.on_site.all()</span></code> will return only the <code class="docutils literal notranslate"><span class="pre">Photo</span></code> objects
associated with the current site, according to the <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SITE_ID</span></code></a> setting.</p>
<p>Put another way, these two statements are equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Photo</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">site</span><span class="o">=</span><span class="n">settings</span><span class="o">.</span><span class="n">SITE_ID</span><span class="p">)</span>
<span class="n">Photo</span><span class="o">.</span><span class="n">on_site</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
</pre></div>
</div>
<p>How did <a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><code class="xref py py-class docutils literal notranslate"><span class="pre">CurrentSiteManager</span></code></a>
know which field of <code class="docutils literal notranslate"><span class="pre">Photo</span></code> was the
<a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a>? By default,
<a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><code class="xref py py-class docutils literal notranslate"><span class="pre">CurrentSiteManager</span></code></a> looks for a
either a <a class="reference internal" href="../models/fields.html#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate"><span class="pre">ForeignKey</span></code></a> called
<code class="docutils literal notranslate"><span class="pre">site</span></code> or a
<a class="reference internal" href="../models/fields.html#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><code class="xref py py-class docutils literal notranslate"><span class="pre">ManyToManyField</span></code></a> called
<code class="docutils literal notranslate"><span class="pre">sites</span></code> to filter on. If you use a field named something other than
<code class="docutils literal notranslate"><span class="pre">site</span></code> or <code class="docutils literal notranslate"><span class="pre">sites</span></code> to identify which
<a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a> objects your object is
related to, then you need to explicitly pass the custom field name as
a parameter to
<a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><code class="xref py py-class docutils literal notranslate"><span class="pre">CurrentSiteManager</span></code></a> on your
model. The following model, which has a field called <code class="docutils literal notranslate"><span class="pre">publish_on</span></code>,
demonstrates this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db</span> <span class="k">import</span> <span class="n">models</span>
<span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="k">import</span> <span class="n">Site</span>
<span class="kn">from</span> <span class="nn">django.contrib.sites.managers</span> <span class="k">import</span> <span class="n">CurrentSiteManager</span>

<span class="k">class</span> <span class="nc">Photo</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="n">photo</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">FileField</span><span class="p">(</span><span class="n">upload_to</span><span class="o">=</span><span class="s1">&#39;photos&#39;</span><span class="p">)</span>
    <span class="n">photographer_name</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    <span class="n">pub_date</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">DateField</span><span class="p">()</span>
    <span class="n">publish_on</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">Site</span><span class="p">,</span> <span class="n">on_delete</span><span class="o">=</span><span class="n">models</span><span class="o">.</span><span class="n">CASCADE</span><span class="p">)</span>
    <span class="n">objects</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">Manager</span><span class="p">()</span>
    <span class="n">on_site</span> <span class="o">=</span> <span class="n">CurrentSiteManager</span><span class="p">(</span><span class="s1">&#39;publish_on&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>If you attempt to use <a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><code class="xref py py-class docutils literal notranslate"><span class="pre">CurrentSiteManager</span></code></a>
and pass a field name that doesn’t exist, Django will raise a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code>.</p>
<p>Finally, note that you’ll probably want to keep a normal
(non-site-specific) <code class="docutils literal notranslate"><span class="pre">Manager</span></code> on your model, even if you use
<a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><code class="xref py py-class docutils literal notranslate"><span class="pre">CurrentSiteManager</span></code></a>. As
explained in the <a class="reference internal" href="../../topics/db/managers.html"><span class="doc">manager documentation</span></a>, if
you define a manager manually, then Django won’t create the automatic
<code class="docutils literal notranslate"><span class="pre">objects</span> <span class="pre">=</span> <span class="pre">models.Manager()</span></code> manager for you. Also note that certain
parts of Django – namely, the Django admin site and generic views –
use whichever manager is defined <em>first</em> in the model, so if you want
your admin site to have access to all objects (not just site-specific
ones), put <code class="docutils literal notranslate"><span class="pre">objects</span> <span class="pre">=</span> <span class="pre">models.Manager()</span></code> in your model, before you
define <a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><code class="xref py py-class docutils literal notranslate"><span class="pre">CurrentSiteManager</span></code></a>.</p>
</div>
<div class="section" id="s-site-middleware">
<span id="s-id2"></span><span id="site-middleware"></span><span id="id2"></span><h2>Site middleware<a class="headerlink" href="#site-middleware" title="Permalink to this headline">¶</a></h2>
<p>If you often use this pattern:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="k">import</span> <span class="n">Site</span>

<span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="n">site</span> <span class="o">=</span> <span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span>
    <span class="o">...</span>
</pre></div>
</div>
<p>there is simple way to avoid repetitions. Add
<a class="reference internal" href="../middleware.html#django.contrib.sites.middleware.CurrentSiteMiddleware" title="django.contrib.sites.middleware.CurrentSiteMiddleware"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.contrib.sites.middleware.CurrentSiteMiddleware</span></code></a> to
<a class="reference internal" href="../settings.html#std:setting-MIDDLEWARE"><code class="xref std std-setting docutils literal notranslate"><span class="pre">MIDDLEWARE</span></code></a>. The middleware sets the <code class="docutils literal notranslate"><span class="pre">site</span></code> attribute on every
request object, so you can use <code class="docutils literal notranslate"><span class="pre">request.site</span></code> to get the current site.</p>
</div>
<div class="section" id="s-how-django-uses-the-sites-framework">
<span id="how-django-uses-the-sites-framework"></span><h2>How Django uses the sites framework<a class="headerlink" href="#how-django-uses-the-sites-framework" title="Permalink to this headline">¶</a></h2>
<p>Although it’s not required that you use the sites framework, it’s strongly
encouraged, because Django takes advantage of it in a few places. Even if your
Django installation is powering only a single site, you should take the two
seconds to create the site object with your <code class="docutils literal notranslate"><span class="pre">domain</span></code> and <code class="docutils literal notranslate"><span class="pre">name</span></code>, and point
to its ID in your <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SITE_ID</span></code></a> setting.</p>
<p>Here’s how Django uses the sites framework:</p>
<ul class="simple">
<li>In the <a class="reference internal" href="redirects.html#module-django.contrib.redirects" title="django.contrib.redirects: A framework for managing redirects."><code class="xref py py-mod docutils literal notranslate"><span class="pre">redirects</span> <span class="pre">framework</span></code></a>, each
redirect object is associated with a particular site. When Django searches
for a redirect, it takes into account the current site.</li>
<li>In the <a class="reference internal" href="flatpages.html#module-django.contrib.flatpages" title="django.contrib.flatpages: A framework for managing simple ?flat? HTML content in a database."><code class="xref py py-mod docutils literal notranslate"><span class="pre">flatpages</span> <span class="pre">framework</span></code></a>, each
flatpage is associated with a particular site. When a flatpage is created,
you specify its <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a>, and the
<a class="reference internal" href="flatpages.html#django.contrib.flatpages.middleware.FlatpageFallbackMiddleware" title="django.contrib.flatpages.middleware.FlatpageFallbackMiddleware"><code class="xref py py-class docutils literal notranslate"><span class="pre">FlatpageFallbackMiddleware</span></code></a>
checks the current site in retrieving flatpages to display.</li>
<li>In the <a class="reference internal" href="syndication.html#module-django.contrib.syndication" title="django.contrib.syndication: A framework for generating syndication feeds, in RSS and Atom, quite easily."><code class="xref py py-mod docutils literal notranslate"><span class="pre">syndication</span> <span class="pre">framework</span></code></a>, the
templates for <code class="docutils literal notranslate"><span class="pre">title</span></code> and <code class="docutils literal notranslate"><span class="pre">description</span></code> automatically have access to a
variable <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">site</span> <span class="pre">}}</span></code>, which is the
<a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a> object representing the current
site. Also, the hook for providing item URLs will use the <code class="docutils literal notranslate"><span class="pre">domain</span></code> from
the current <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a> object if you don’t
specify a fully-qualified domain.</li>
<li>In the <a class="reference internal" href="../../topics/auth/index.html#module-django.contrib.auth" title="django.contrib.auth: Django's authentication framework."><code class="xref py py-mod docutils literal notranslate"><span class="pre">authentication</span> <span class="pre">framework</span></code></a>,
<a class="reference internal" href="../../topics/auth/default.html#django.contrib.auth.views.LoginView" title="django.contrib.auth.views.LoginView"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.contrib.auth.views.LoginView</span></code></a> passes the current
<a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a> name to the template as
<code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">site_name</span> <span class="pre">}}</span></code>.</li>
<li>The shortcut view (<code class="docutils literal notranslate"><span class="pre">django.contrib.contenttypes.views.shortcut</span></code>)
uses the domain of the current
<a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a> object when calculating
an object’s URL.</li>
<li>In the admin framework, the “view on site” link uses the current
<a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a> to work out the domain for the
site that it will redirect to.</li>
</ul>
</div>
<div class="section" id="s-requestsite-objects">
<span id="requestsite-objects"></span><h2><code class="docutils literal notranslate"><span class="pre">RequestSite</span></code> objects<a class="headerlink" href="#requestsite-objects" title="Permalink to this headline">¶</a></h2>
<p id="id3">Some <a class="reference internal" href="index.html"><span class="doc">django.contrib</span></a> applications take advantage of
the sites framework but are architected in a way that doesn’t <em>require</em> the
sites framework to be installed in your database. (Some people don’t want to,
or just aren’t <em>able</em> to install the extra database table that the sites
framework requires.) For those cases, the framework provides a
<a class="reference internal" href="#django.contrib.sites.requests.RequestSite" title="django.contrib.sites.requests.RequestSite"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.contrib.sites.requests.RequestSite</span></code></a> class, which can be used as
a fallback when the database-backed sites framework is not available.</p>
<dl class="class">
<dt id="django.contrib.sites.requests.RequestSite">
<em class="property">class </em><code class="descclassname">requests.</code><code class="descname">RequestSite</code><a class="headerlink" href="#django.contrib.sites.requests.RequestSite" title="Permalink to this definition">¶</a></dt>
<dd><p>A class that shares the primary interface of
<a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a> (i.e., it has
<code class="docutils literal notranslate"><span class="pre">domain</span></code> and <code class="docutils literal notranslate"><span class="pre">name</span></code> attributes) but gets its data from a Django
<a class="reference internal" href="../request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpRequest</span></code></a> object rather than from a database.</p>
<dl class="method">
<dt id="django.contrib.sites.requests.RequestSite.__init__">
<code class="descname">__init__</code>(<em>request</em>)<a class="headerlink" href="#django.contrib.sites.requests.RequestSite.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Sets the <code class="docutils literal notranslate"><span class="pre">name</span></code> and <code class="docutils literal notranslate"><span class="pre">domain</span></code> attributes to the value of
<a class="reference internal" href="../request-response.html#django.http.HttpRequest.get_host" title="django.http.HttpRequest.get_host"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_host()</span></code></a>.</p>
</dd></dl>

</dd></dl>

<p>A <a class="reference internal" href="#django.contrib.sites.requests.RequestSite" title="django.contrib.sites.requests.RequestSite"><code class="xref py py-class docutils literal notranslate"><span class="pre">RequestSite</span></code></a> object has a similar
interface to a normal <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a> object,
except its <a class="reference internal" href="#django.contrib.sites.requests.RequestSite.__init__" title="django.contrib.sites.requests.RequestSite.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a>
method takes an <a class="reference internal" href="../request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpRequest</span></code></a> object. It’s able to deduce
the <code class="docutils literal notranslate"><span class="pre">domain</span></code> and <code class="docutils literal notranslate"><span class="pre">name</span></code> by looking at the request’s domain. It has
<code class="docutils literal notranslate"><span class="pre">save()</span></code> and <code class="docutils literal notranslate"><span class="pre">delete()</span></code> methods to match the interface of
<a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a>, but the methods raise
<a class="reference external" href="https://docs.python.org/3/library/exceptions.html#NotImplementedError" title="(in Python v3.7)"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a>.</p>
</div>
<div class="section" id="s-get-current-site-shortcut">
<span id="get-current-site-shortcut"></span><h2><code class="docutils literal notranslate"><span class="pre">get_current_site</span></code> shortcut<a class="headerlink" href="#get-current-site-shortcut" title="Permalink to this headline">¶</a></h2>
<p>Finally, to avoid repetitive fallback code, the framework provides a
<a class="reference internal" href="#django.contrib.sites.shortcuts.get_current_site" title="django.contrib.sites.shortcuts.get_current_site"><code class="xref py py-func docutils literal notranslate"><span class="pre">django.contrib.sites.shortcuts.get_current_site()</span></code></a> function.</p>
<dl class="function">
<dt id="django.contrib.sites.shortcuts.get_current_site">
<code class="descclassname">shortcuts.</code><code class="descname">get_current_site</code>(<em>request</em>)<a class="headerlink" href="#django.contrib.sites.shortcuts.get_current_site" title="Permalink to this definition">¶</a></dt>
<dd><p>A function that checks if <code class="docutils literal notranslate"><span class="pre">django.contrib.sites</span></code> is installed and
returns either the current <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><code class="xref py py-class docutils literal notranslate"><span class="pre">Site</span></code></a>
object or a <a class="reference internal" href="#django.contrib.sites.requests.RequestSite" title="django.contrib.sites.requests.RequestSite"><code class="xref py py-class docutils literal notranslate"><span class="pre">RequestSite</span></code></a> object
based on the request. It looks up the current site based on
<a class="reference internal" href="../request-response.html#django.http.HttpRequest.get_host" title="django.http.HttpRequest.get_host"><code class="xref py py-meth docutils literal notranslate"><span class="pre">request.get_host()</span></code></a> if the
<a class="reference internal" href="../settings.html#std:setting-SITE_ID"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SITE_ID</span></code></a> setting is not defined.</p>
<p>Both a domain and a port may be returned by <a class="reference internal" href="../request-response.html#django.http.HttpRequest.get_host" title="django.http.HttpRequest.get_host"><code class="xref py py-meth docutils literal notranslate"><span class="pre">request.get_host()</span></code></a> when the Host header has a port
explicitly specified, e.g. <code class="docutils literal notranslate"><span class="pre">example.com:80</span></code>. In such cases, if the
lookup fails because the host does not match a record in the database,
the port is stripped and the lookup is retried with the domain part
only. This does not apply to
<a class="reference internal" href="#django.contrib.sites.requests.RequestSite" title="django.contrib.sites.requests.RequestSite"><code class="xref py py-class docutils literal notranslate"><span class="pre">RequestSite</span></code></a> which will always
use the unmodified host.</p>
</dd></dl>

</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">The “sites” framework</a><ul>
<li><a class="reference internal" href="#example-usage">Example usage</a><ul>
<li><a class="reference internal" href="#associating-content-with-multiple-sites">Associating content with multiple sites</a></li>
<li><a class="reference internal" href="#associating-content-with-a-single-site">Associating content with a single site</a></li>
<li><a class="reference internal" href="#hooking-into-the-current-site-from-views">Hooking into the current site from views</a></li>
<li><a class="reference internal" href="#getting-the-current-domain-for-display">Getting the current domain for display</a></li>
<li><a class="reference internal" href="#getting-the-current-domain-for-full-urls">Getting the current domain for full URLs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#enabling-the-sites-framework">Enabling the sites framework</a></li>
<li><a class="reference internal" href="#caching-the-current-site-object">Caching the current <code class="docutils literal notranslate"><span class="pre">Site</span></code> object</a></li>
<li><a class="reference internal" href="#the-currentsitemanager">The <code class="docutils literal notranslate"><span class="pre">CurrentSiteManager</span></code></a></li>
<li><a class="reference internal" href="#site-middleware">Site middleware</a></li>
<li><a class="reference internal" href="#how-django-uses-the-sites-framework">How Django uses the sites framework</a></li>
<li><a class="reference internal" href="#requestsite-objects"><code class="docutils literal notranslate"><span class="pre">RequestSite</span></code> objects</a></li>
<li><a class="reference internal" href="#get-current-site-shortcut"><code class="docutils literal notranslate"><span class="pre">get_current_site</span></code> shortcut</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="sitemaps.html"
                        title="previous chapter">The sitemap framework</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="staticfiles.html"
                        title="next chapter">The <code class="docutils literal notranslate"><span class="pre">staticfiles</span></code> app</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../../_sources/ref/contrib/sites.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Jun 03, 2019</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="sitemaps.html" title="The sitemap framework">previous</a>
     |
    <a href="../index.html" title="API Reference" accesskey="U">up</a>
   |
    <a href="staticfiles.html" title="The &lt;code class=&#34;docutils literal notranslate&#34;&gt;&lt;span class=&#34;pre&#34;&gt;staticfiles&lt;/span&gt;&lt;/code&gt; app">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>